<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd">
<html>
 <head>
  <meta http-equiv="content-type" content="text/html; charset=UTF-8">
  <title>执行一个命令，并且打开用来输入/输出的文件指针。</title>
<link media="all" rel="stylesheet" type="text/css" href="styles/03e73060321a0a848018724a6c83de7f-theme-base.css" />
<link media="all" rel="stylesheet" type="text/css" href="styles/03e73060321a0a848018724a6c83de7f-theme-medium.css" />

 </head>
 <body class="docs"><div class="navbar navbar-fixed-top">
  <div class="navbar-inner clearfix">
    <ul class="nav" style="width: 100%">
      <li style="float: left;"><a href="function.proc-nice.html">« proc_nice</a></li>
      <li style="float: right;"><a href="function.proc-terminate.html">proc_terminate »</a></li>
    </ul>
  </div>
</div>
<div id="breadcrumbs" class="clearfix">
  <ul class="breadcrumbs-container">
    <li><a href="index.html">PHP Manual</a></li>
    <li><a href="ref.exec.html">程序执行函数</a></li>
    <li>执行一个命令，并且打开用来输入/输出的文件指针。</li>
  </ul>
</div>
<div id="layout">
  <div id="layout-content"><div id="function.proc-open" class="refentry">
   <div class="refnamediv">
    <h1 class="refname">proc_open</h1>
    <p class="verinfo">(PHP 4 &gt;= 4.3.0, PHP 5, PHP 7, PHP 8)</p><p class="refpurpose"><span class="refname">proc_open</span> &mdash; <span class="dc-title">
     执行一个命令，并且打开用来输入/输出的文件指针。
    </span></p>

   </div>
   <div class="refsect1 description" id="refsect1-function.proc-open-description">
    <h3 class="title">说明</h3>
     <div class="methodsynopsis dc-description">
   <span class="methodname"><strong>proc_open</strong></span>(<br>&nbsp;&nbsp;&nbsp;&nbsp;<span class="methodparam"><span class="type"><span class="type">array</span>|<span class="type">string</span></span> <code class="parameter">$command</code></span>,<br>&nbsp;&nbsp;&nbsp;&nbsp;<span class="methodparam"><span class="type">array</span> <code class="parameter">$descriptor_spec</code></span>,<br>&nbsp;&nbsp;&nbsp;&nbsp;<span class="methodparam"><span class="type">array</span> <code class="parameter reference">&$pipes</code></span>,<br>&nbsp;&nbsp;&nbsp;&nbsp;<span class="methodparam"><span class="type">?</span><span class="type"><span class="type">string</span><span class="type"></span></span> <code class="parameter">$cwd</code><span class="initializer"> = <strong><code>null</code></strong></span></span>,<br>&nbsp;&nbsp;&nbsp;&nbsp;<span class="methodparam"><span class="type">?</span><span class="type"><span class="type">array</span><span class="type"></span></span> <code class="parameter">$env_vars</code><span class="initializer"> = <strong><code>null</code></strong></span></span>,<br>&nbsp;&nbsp;&nbsp;&nbsp;<span class="methodparam"><span class="type">?</span><span class="type"><span class="type">array</span><span class="type"></span></span> <code class="parameter">$options</code><span class="initializer"> = <strong><code>null</code></strong></span></span><br>): <span class="type"><span class="type">resource</span>|<span class="type"><span class="type false">false</span></span></span></div>

    <p class="para rdfs-comment">
     类似 <span class="function"><a href="function.popen.html" class="function">popen()</a></span> 函数，
     但是 <span class="function"><strong>proc_open()</strong></span> 提供了更加强大的控制程序执行的能力。
    </p>



   </div>


 <div class="refsect1 parameters" id="refsect1-function.proc-open-parameters">
  <h3 class="title">参数</h3>
  <p class="para">
   <dl>
    
     <dt>
<code class="parameter">command</code></dt>

     <dd>

      <p class="para">
       以 <span class="type">string</span> 形式执行的命令行。特殊字符必须经过转义，并且使用正确的引号。
      </p>
      <blockquote class="note"><p><strong class="note">注意</strong>: 
       <span class="simpara">
        在 <em class="emphasis">Windows</em> 上, 除非在 <code class="parameter">options</code> 中
        把 <code class="literal">bypass_shell</code> 设置为  <strong><code>true</code></strong>
        ，否则 <code class="parameter">command</code> 会被传递给 <strong class="command">cmd.exe</strong> （实际上是 <code class="literal">%ComSpec%</code>）
        其中的 <code class="literal">/c</code> 标志是 <em class="emphasis">未加引号的</em> 字符串 （也就是和 <span class="function"><strong>proc_open()</strong></span> 一样）。
        这可能会导致 <strong class="command">cmd.exe</strong> 删除 <code class="parameter">command</code> 中的引号 （详见 <strong class="command">cmd.exe</strong> 文档），
        从而导致意外的，甚至是潜在的危险行为，因为
        <strong class="command">cmd.exe</strong> 错误消息可能包含 （部分） 传递的 <code class="parameter">command</code> （见下面的例子）。
       </span>
      </p></blockquote>
      <p class="para">
       从 PHP 7.4.0 开始，<code class="parameter">command</code> 参数可以使用 <span class="type">array</span> 类型传递。
       在这种情况下，进程将直接打开（不通过 shell ）。
       而 PHP 会处理任何必要的参数转义。
      </p>
      <blockquote class="note"><p><strong class="note">注意</strong>: 
       <p class="para">
        在 Windows 上， <span class="type">array</span> 元素的参数转义假定
        执行命令的命令行解析与 VC 运行时进行的命令行参数解析兼容。
       </p>
      </p></blockquote>
     </dd>

    
    
     <dt>
<code class="parameter">descriptor_spec</code></dt>

     <dd>

      <p class="para">
        一个索引数组。
        数组的键表示描述符，数组元素值表示 PHP 如何将这些描述符传送至子进程。
        0 表示标准输入（stdin），1 表示标准输出（stdout），2 表示标准错误（stderr）。
      </p>
      <p class="para">
       数组中的元素可以是：
       <ul class="simplelist">
        <li class="member">   
         包含了要传送至进程的管道的描述信息的数组。第一个元素为描述符类型，第二个元素是针对该描述符的选项。有效的类型有：<code class="literal">pipe</code>（第二个元素可以是：<code class="literal">r</code>
         向进程传送该管道的读取端，<code class="literal">w</code> 向进程传送该管道的写入端），以及
         <code class="literal">file</code>（第二个元素为文件名）。注意除了 <code class="literal">w</code>
         之外的任何内容都视为 <code class="literal">r</code>。
        </li>
        <li class="member">
          流资源表示真实文件描述符（例如：已打开的文件，套接字，<strong><code>STDIN</code></strong>）。
        </li>
       </ul>
      </p>
      <p class="para">
        文件描述符的值不限于 0，1 和 2，你可以使用任何有效的文件描述符
        并将其传送至子进程。
        这使得你的脚本可以和其他脚本交互操作。
        例如，可以通过指定文件描述符将密码以更加安全的方式
        传送至诸如 PGP，GPG 和 openssl 程序，
        同时也可以很方便的获取这些程序的状态信息。
      </p>
     </dd>

    
    
     <dt>
<code class="parameter">pipes</code></dt>

     <dd>

      <p class="para">
        将被置为索引数组，
        其中的元素是被执行程序创建的管道对应到 PHP 这一端的文件指针。
      </p>
     </dd>

    
    
     <dt>
<code class="parameter">cwd</code></dt>

     <dd>

      <p class="para">
        要执行命令的初始工作目录。
        必须是 <em class="emphasis">绝对</em> 路径，
        设置此参数为 <strong><code>null</code></strong> 
        表示使用默认值（当前 PHP 进程的工作目录）。
      </p>
     </dd>

    
    
     <dt>
<code class="parameter">env_vars</code></dt>

     <dd>

      <p class="para">
        要执行的命令所使用的环境变量。
        设置此参数为 <strong><code>null</code></strong> 表示使用和当前 PHP 进程相同的环境变量。
      </p>
     </dd>

    
    
     <dt>
<code class="parameter">options</code></dt>

     <dd>

      <p class="para">
        你还可以指定一些附加选项。
        目前支持的选项包括：
       <ul class="simplelist">
        <li class="member">
         <code class="literal">suppress_errors</code> （仅用于 Windows 平台）：
         设置为 <strong><code>true</code></strong> 表示抑制本函数产生的错误。
        </li>
        <li class="member">
         <code class="literal">bypass_shell</code> （仅用于 Windows 平台）：
         设置为 <strong><code>true</code></strong> 表示绕过 <code class="literal">cmd.exe</code> shell。
        </li>
        <li class="member">
         <code class="literal">blocking_pipes</code> （仅用于 Windows 平台）：
         设置为 <strong><code>true</code></strong> 表示强制堵塞管道。
        </li>
        <li class="member">
         <code class="literal">create_process_group</code> （仅用于 Windows 平台）：
         设置为 <strong><code>true</code></strong> 表示允许子进程处理 <code class="literal">CTRL</code> 事件。
        </li>
        <li class="member">
         <code class="literal">create_new_console</code> （仅用于 Windows 平台）：
         表示新进程有一个新的控制台，用于代替父进程的控制台。
        </li>
       </ul>
      </p>
     </dd>

    
   </dl>

  </p>
 </div>


 <div class="refsect1 returnvalues" id="refsect1-function.proc-open-returnvalues">
  <h3 class="title">返回值</h3>
  <p class="para">
    返回表示进程的资源类型，
    当使用完毕之后，请调用 <span class="function"><a href="function.proc-close.html" class="function">proc_close()</a></span> 函数来关闭此资源。
    如果失败，返回 <strong><code>false</code></strong>。
  </p>
 </div>


 <div class="refsect1 changelog" id="refsect1-function.proc-open-changelog">
  <h3 class="title">更新日志</h3>
  <p class="para">
   <table class="doctable informaltable">
    
     <thead>
      <tr>
       <th>版本</th>
       <th>说明</th>
      </tr>

     </thead>

     <tbody class="tbody">
      <tr>
       <td>7.4.4</td>
       <td>
        为 <code class="parameter">options</code> 参数增加 <code class="literal">create_new_console</code> 选项。
       </td>
      </tr>

      <tr>
       <td>7.4.0</td>
       <td>
        <span class="function"><strong>proc_open()</strong></span> 的 <code class="parameter">command</code> 参数现在也允许数组类型。
       </td>
      </tr>

      <tr>
       <td>7.4.0</td>
       <td>
        为 <code class="parameter">options</code> 参数增加 <code class="literal">create_process_group</code> 选项。
       </td>
      </tr>

     </tbody>
    
   </table>

  </p>
 </div>


 <div class="refsect1 examples" id="refsect1-function.proc-open-examples">
  <h3 class="title">范例</h3>
  <p class="para">
   <div class="example" id="example-3310">
    <p><strong>示例 #1 <span class="function"><strong>proc_open()</strong></span> 例程</strong></p>
    <div class="example-contents">
<div class="phpcode"><code><span style="color: #000000">
<span style="color: #0000BB">&lt;?php<br />$descriptorspec&nbsp;</span><span style="color: #007700">=&nbsp;array(<br />&nbsp;&nbsp;&nbsp;</span><span style="color: #0000BB">0&nbsp;</span><span style="color: #007700">=&gt;&nbsp;array(</span><span style="color: #DD0000">"pipe"</span><span style="color: #007700">,&nbsp;</span><span style="color: #DD0000">"r"</span><span style="color: #007700">),&nbsp;&nbsp;</span><span style="color: #FF8000">//&nbsp;标准输入，子进程从此管道中读取数据<br />&nbsp;&nbsp;&nbsp;</span><span style="color: #0000BB">1&nbsp;</span><span style="color: #007700">=&gt;&nbsp;array(</span><span style="color: #DD0000">"pipe"</span><span style="color: #007700">,&nbsp;</span><span style="color: #DD0000">"w"</span><span style="color: #007700">),&nbsp;&nbsp;</span><span style="color: #FF8000">//&nbsp;标准输出，子进程向此管道中写入数据<br />&nbsp;&nbsp;&nbsp;</span><span style="color: #0000BB">2&nbsp;</span><span style="color: #007700">=&gt;&nbsp;array(</span><span style="color: #DD0000">"file"</span><span style="color: #007700">,&nbsp;</span><span style="color: #DD0000">"/tmp/error-output.txt"</span><span style="color: #007700">,&nbsp;</span><span style="color: #DD0000">"a"</span><span style="color: #007700">)&nbsp;</span><span style="color: #FF8000">//&nbsp;标准错误，写入到一个文件<br /></span><span style="color: #007700">);<br /><br /></span><span style="color: #0000BB">$cwd&nbsp;</span><span style="color: #007700">=&nbsp;</span><span style="color: #DD0000">'/tmp'</span><span style="color: #007700">;<br /></span><span style="color: #0000BB">$env&nbsp;</span><span style="color: #007700">=&nbsp;array(</span><span style="color: #DD0000">'some_option'&nbsp;</span><span style="color: #007700">=&gt;&nbsp;</span><span style="color: #DD0000">'aeiou'</span><span style="color: #007700">);<br /><br /></span><span style="color: #0000BB">$process&nbsp;</span><span style="color: #007700">=&nbsp;</span><span style="color: #0000BB">proc_open</span><span style="color: #007700">(</span><span style="color: #DD0000">'php'</span><span style="color: #007700">,&nbsp;</span><span style="color: #0000BB">$descriptorspec</span><span style="color: #007700">,&nbsp;</span><span style="color: #0000BB">$pipes</span><span style="color: #007700">,&nbsp;</span><span style="color: #0000BB">$cwd</span><span style="color: #007700">,&nbsp;</span><span style="color: #0000BB">$env</span><span style="color: #007700">);<br /><br />if&nbsp;(</span><span style="color: #0000BB">is_resource</span><span style="color: #007700">(</span><span style="color: #0000BB">$process</span><span style="color: #007700">))&nbsp;{<br />&nbsp;&nbsp;&nbsp;&nbsp;</span><span style="color: #FF8000">//&nbsp;$pipes&nbsp;现在看起来是这样的：<br />&nbsp;&nbsp;&nbsp;&nbsp;//&nbsp;0&nbsp;=&gt;&nbsp;可以向子进程标准输入写入的句柄<br />&nbsp;&nbsp;&nbsp;&nbsp;//&nbsp;1&nbsp;=&gt;&nbsp;可以从子进程标准输出读取的句柄<br />&nbsp;&nbsp;&nbsp;&nbsp;//&nbsp;错误输出将被追加到文件&nbsp;/tmp/error-output.txt<br /><br />&nbsp;&nbsp;&nbsp;&nbsp;</span><span style="color: #0000BB">fwrite</span><span style="color: #007700">(</span><span style="color: #0000BB">$pipes</span><span style="color: #007700">[</span><span style="color: #0000BB">0</span><span style="color: #007700">],&nbsp;</span><span style="color: #DD0000">'&lt;?php&nbsp;print_r($_ENV);&nbsp;?&gt;'</span><span style="color: #007700">);<br />&nbsp;&nbsp;&nbsp;&nbsp;</span><span style="color: #0000BB">fclose</span><span style="color: #007700">(</span><span style="color: #0000BB">$pipes</span><span style="color: #007700">[</span><span style="color: #0000BB">0</span><span style="color: #007700">]);<br /><br />&nbsp;&nbsp;&nbsp;&nbsp;echo&nbsp;</span><span style="color: #0000BB">stream_get_contents</span><span style="color: #007700">(</span><span style="color: #0000BB">$pipes</span><span style="color: #007700">[</span><span style="color: #0000BB">1</span><span style="color: #007700">]);<br />&nbsp;&nbsp;&nbsp;&nbsp;</span><span style="color: #0000BB">fclose</span><span style="color: #007700">(</span><span style="color: #0000BB">$pipes</span><span style="color: #007700">[</span><span style="color: #0000BB">1</span><span style="color: #007700">]);<br />&nbsp;&nbsp;&nbsp;&nbsp;<br /><br />&nbsp;&nbsp;&nbsp;&nbsp;</span><span style="color: #FF8000">//&nbsp;切记：在调用&nbsp;proc_close&nbsp;之前关闭所有的管道以避免死锁。<br />&nbsp;&nbsp;&nbsp;&nbsp;</span><span style="color: #0000BB">$return_value&nbsp;</span><span style="color: #007700">=&nbsp;</span><span style="color: #0000BB">proc_close</span><span style="color: #007700">(</span><span style="color: #0000BB">$process</span><span style="color: #007700">);<br /><br />&nbsp;&nbsp;&nbsp;&nbsp;echo&nbsp;</span><span style="color: #DD0000">"command&nbsp;returned&nbsp;</span><span style="color: #0000BB">$return_value</span><span style="color: #DD0000">\n"</span><span style="color: #007700">;<br />}<br /></span><span style="color: #0000BB">?&gt;</span>
</span>
</code></div>
    </div>

    <div class="example-contents"><p>以上例程的输出类似于：</p></div>
    <div class="example-contents screen">
<div class="cdata"><pre>
Array
(
    [some_option] =&gt; aeiou
    [PWD] =&gt; /tmp
    [SHLVL] =&gt; 1
    [_] =&gt; /usr/local/bin/php
)
command returned 0
</pre></div>
    </div>
   </div>
  </p>

  <p class="para">
   <div class="example" id="example-3311">
    <p><strong>示例 #2 <span class="function"><strong>proc_open()</strong></span> 在 Windows 上的怪异行为</strong></p>
    <div class="example-contents"><p>
     虽然人们可能期望下面的程序能够搜索文件
     <var class="filename">filename.txt</var> 进行文本搜索，
     并打印结果，但它的行为相当不同。
    </p></div>
    <div class="example-contents">
     <div class="phpcode"><code><span style="color: #000000">
<span style="color: #0000BB">&lt;?php<br />$descriptorspec&nbsp;</span><span style="color: #007700">=&nbsp;[</span><span style="color: #0000BB">STDIN</span><span style="color: #007700">,&nbsp;</span><span style="color: #0000BB">STDOUT</span><span style="color: #007700">,&nbsp;</span><span style="color: #0000BB">STDOUT</span><span style="color: #007700">];<br /></span><span style="color: #0000BB">$cmd&nbsp;</span><span style="color: #007700">=&nbsp;</span><span style="color: #DD0000">'"findstr"&nbsp;"search"&nbsp;"filename.txt"'</span><span style="color: #007700">;<br /></span><span style="color: #0000BB">$proc&nbsp;</span><span style="color: #007700">=&nbsp;</span><span style="color: #0000BB">proc_open</span><span style="color: #007700">(</span><span style="color: #0000BB">$cmd</span><span style="color: #007700">,&nbsp;</span><span style="color: #0000BB">$descriptorspec</span><span style="color: #007700">,&nbsp;</span><span style="color: #0000BB">$pipes</span><span style="color: #007700">);<br /></span><span style="color: #0000BB">proc_close</span><span style="color: #007700">(</span><span style="color: #0000BB">$proc</span><span style="color: #007700">);<br /></span><span style="color: #0000BB">?&gt;</span>
</span>
</code></div>
    </div>

    <div class="example-contents"><p>以上例程会输出：</p></div>
    <div class="example-contents screen">
     <div class="cdata"><pre>
&#039;findstr&quot; &quot;search&quot; &quot;filename.txt&#039; is not recognized as an internal or external command,
operable program or batch file.
</pre></div>
    </div>
    <div class="example-contents"><p>
     要解决该行为，通常只需将 <code class="parameter">command</code> 加上引号：
    </p></div>
    <div class="example-contents">
     <div class="phpcode"><code><span style="color: #000000">
$cmd&nbsp;=&nbsp;'""findstr"&nbsp;"search"&nbsp;"filename.txt""';</span>
</code></div>
    </div>

   </div>
  </p>



 </div>


 <div class="refsect1 notes" id="refsect1-function.proc-open-notes">
  <h3 class="title">注释</h3>
  <blockquote class="note"><p><strong class="note">注意</strong>: 
   <p class="para">
    Windows 兼容性：超过 2 的描述符也可以作为可继承的句柄传送到子进程。
    但是，由于 Windows 的架构并不将文件描述符和底层句柄进行关联，
    所以，子进程无法访问这样的句柄。
    标准输入，标准输出和标注错误会按照预期工作。
   </p>
  </p></blockquote>
  <blockquote class="note"><p><strong class="note">注意</strong>: 
   <p class="para">
    如果你只需要单向的进程管道，
    使用 <span class="function"><a href="function.popen.html" class="function">popen()</a></span> 函数会更加简单。
   </p>
  </p></blockquote>
 </div>

 
 <div class="refsect1 seealso" id="refsect1-function.proc-open-seealso">
  <h3 class="title">参见</h3>
  <p class="para">
   <ul class="simplelist">
    <li class="member"><span class="function"><a href="function.popen.html" class="function" rel="rdfs-seeAlso">popen()</a> - 打开进程文件指针</span></li>
    <li class="member"><span class="function"><a href="function.exec.html" class="function" rel="rdfs-seeAlso">exec()</a> - 执行一个外部程序</span></li>
    <li class="member"><span class="function"><a href="function.system.html" class="function" rel="rdfs-seeAlso">system()</a> - 执行外部程序，并且显示输出</span></li>
    <li class="member"><span class="function"><a href="function.passthru.html" class="function" rel="rdfs-seeAlso">passthru()</a> - 执行外部程序并且显示原始输出</span></li>
    <li class="member"><span class="function"><a href="function.stream-select.html" class="function" rel="rdfs-seeAlso">stream_select()</a> - Runs the equivalent of the select() system call on the given
   arrays of streams with a timeout specified by seconds and microseconds</span></li>
    <li class="member">The <a href="language.operators.execution.html" class="link">执行运算符</a></li>
   </ul>
  </p>
 </div>

</div></div></div></body></html>